fork-ts-checker-webpack-plugin

What is fork-ts-checker-webpack-plugin?

The fork-ts-checker-webpack-plugin is a plugin for webpack that runs TypeScript type checking on a separate process. This allows you to get type checking results while webpack compiles your code, improving build speed by utilizing multiple CPU cores. It also integrates with ESLint to provide linting for both TypeScript and JavaScript files.

What are fork-ts-checker-webpack-plugin's main functionalities?

TypeScript Type Checking

This feature runs TypeScript type checking in a separate process to speed up the webpack build.

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  plugins: [new ForkTsCheckerWebpackPlugin()],
};

ESLint Integration

This feature allows the plugin to run ESLint on your code in parallel with the TypeScript type checker.

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

module.exports = {
  plugins: [
    new ForkTsCheckerWebpackPlugin({
      eslint: {
        files: './src/**/*.{ts,tsx,js,jsx}'
      }
    })
  ],
};

Asynchronous Reporting

This feature provides asynchronous reporting of type checking and linting results, so they do not block webpack's compilation process.

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
const webpack = require('webpack');

const compiler = webpack({
  // ...webpack configuration
  plugins: [new ForkTsCheckerWebpackPlugin()],
});

compiler.run((error, stats) => {
  // ...handle webpack build result
});

Other packages similar to fork-ts-checker-webpack-plugin

ts-loader

ts-loader is a TypeScript loader for webpack. It is responsible for compiling TypeScript files to JavaScript. Unlike fork-ts-checker-webpack-plugin, ts-loader does the type checking in the main compilation process, which can be slower for large projects.

awesome-typescript-loader

awesome-typescript-loader is another TypeScript loader for webpack. Similar to ts-loader, it provides compilation of TypeScript files. It also offers features like Babel integration and can use a separate process for type checking, but it is not as actively maintained as fork-ts-checker-webpack-plugin.

eslint-webpack-plugin

eslint-webpack-plugin is a plugin for webpack that provides linting functionality. It integrates ESLint into the webpack build process. While it does not offer TypeScript type checking, it serves a similar purpose for linting as fork-ts-checker-webpack-plugin does when the ESLint integration is enabled.

README

Fork TS Checker Webpack Plugin

Webpack plugin that runs TypeScript type checker on a separate process.

Installation

This plugin requires minimum Node.js 6.11.5, webpack 4, TypeScript 2.1 and optionally ESLint 6 (which itself requires minimum Node.js 8.10.0)

If you depend on webpack 2, webpack 3, or tslint 4, please use older version of the plugin.

# with npm
npm install --save-dev fork-ts-checker-webpack-plugin

# with yarn
yarn add --dev fork-ts-checker-webpack-plugin

Basic webpack config (with ts-loader)

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');

const webpackConfig = {
  context: __dirname, // to automatically find tsconfig.json
  entry: './src/index.ts',
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'ts-loader',
        options: {
          // disable type checker - we will use it in fork plugin
          transpileOnly: true
        }
      }
    ]
  },
  plugins: [new ForkTsCheckerWebpackPlugin()]
};

Motivation

There was already similar solution - awesome-typescript-loader. You can add CheckerPlugin and delegate checker to the separate process. The problem with awesome-typescript-loader was that, in our case, it was a lot slower than ts-loader on an incremental build (~20s vs ~3s). Secondly, we used tslint and we wanted to run this, along with type checker, in a separate process. This is why this plugin was created. To provide better performance, the plugin reuses Abstract Syntax Trees between compilations and shares these trees with TSLint.

Modules resolution

It's very important to be aware that this plugin uses TypeScript's, not webpack's modules resolution. It means that you have to setup tsconfig.json correctly. For example if you set files: ['./src/someFile.ts'] in tsconfig.json, this plugin will check only someFile.ts for semantic errors. It's because of performance. The goal of this plugin is to be as fast as possible. With TypeScript's module resolution we don't have to wait for webpack to compile files (which traverses dependency graph during compilation) - we have a full list of files from the begin.

To debug TypeScript's modules resolution, you can use tsc --traceResolution command.

ESLint

ESLint is the future of linting in the TypeScript world. If you'd like to use eslint with the plugin, supply this option: eslint: true and ensure you have the relevant dependencies installed:

yarn add eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin --dev

You should have an ESLint configuration file in your root project directory. Here is a sample .eslintrc.js configuration for a TypeScript project:

const path = require('path');
module.exports = {
  parser: '@typescript-eslint/parser', // Specifies the ESLint parser
  extends: [
    'plugin:@typescript-eslint/recommended' // Uses the recommended rules from the @typescript-eslint/eslint-plugin
  ],
  parserOptions: {
    project: path.resolve(__dirname, './tsconfig.json'),
    tsconfigRootDir: __dirname,
    ecmaVersion: 2018, // Allows for the parsing of modern ECMAScript features
    sourceType: 'module', // Allows for the use of imports
  },
  rules: {
    // Place to specify ESLint rules. Can be used to overwrite rules specified from the extended configs
    // e.g. "@typescript-eslint/explicit-function-return-type": "off",
  }
};

There's a good explanation on setting up TypeScript ESLint support by Robert Cooper here.

Options

• tsconfig string: Path to tsconfig.json file. Default: path.resolve(compiler.options.context, './tsconfig.json').

• compilerOptions object: Allows overriding TypeScript options. Should be specified in the same format as you would do for the compilerOptions property in tsconfig.json. Default: {}.

• eslint true | undefined:

  • If true, this activates eslint support.

• eslintOptions object:

  • Options that can be used to initialise ESLint. See https://eslint.org/docs/developer-guide/nodejs-api#cliengine

• async boolean: True by default - async: false can block webpack's emit to wait for type checker/linter and to add errors to the webpack's compilation. We recommend to set this to false in projects where type checking is faster than webpack's build - it's better for integration with other plugins. Another scenario where you might want to set this to false is if you use the overlay functionality of webpack-dev-server.

• ignoreDiagnostics number[]: List of TypeScript diagnostic codes to ignore.

• ignoreLints string[]: List of eslint rule names to ignore.

• ignoreLintWarnings boolean: If true, will ignore all lint warnings.

• reportFiles string[]: Only report errors on files matching these glob patterns. This can be useful when certain types definitions have errors that are not fatal to your application. Default: []. Please note that this may behave unexpectedly if using the incremental API as the incremental API doesn't look for global and semantic errors if it has already found syntactic errors.

// in webpack.config.js
new ForkTsCheckerWebpackPlugin({
  reportFiles: ['src/**/*.{ts,tsx}', '!src/skip.ts']
});

• logger object: Logger instance. It should be object that implements method: error, warn, info. Default: console.

• formatter 'default' | 'codeframe' | (issue: Issue) => string): Formatter for issues and lints. By default uses default formatter. You can also pass your own formatter as a function (see src/issue/ and src/formatter/ for API reference).

• formatterOptions object: Options passed to formatters (currently only codeframe - see available options)

• silent boolean: If true, logger will not be used. Default: false.

• checkSyntacticErrors boolean: This option is useful if you're using ts-loader in happyPackMode with HappyPack or thread-loader to parallelise your builds. If true it will ensure that the plugin checks for both syntactic errors (eg const array = [{} {}];) and semantic errors (eg const x: number = '1';). By default the plugin only checks for semantic errors. This is because when ts-loader is used in transpileOnly mode, ts-loader will still report syntactic errors. When used in happyPackMode it does not. Default: false.

• memoryLimit number: Memory limit for service process in MB. If service exits with allocation failed error, increase this number. Default: 2048.

• vue boolean | { enabled: boolean, compiler: string }: If true or enabled: true, the linter and compiler will process VueJs single-file-component (.vue) files. See the Vue section further down for information on how to correctly setup your project.

• useTypescriptIncrementalApi boolean: If true, the plugin will use incremental compilation API introduced in TypeScript 2.7. Defaults to true when working with TypeScript 3+ and false when below 3. The default can be overridden by directly specifying a value. Don't use it together with VueJs enabled - it's not supported yet.

• measureCompilationTime boolean: If true, the plugin will measure the time spent inside the compilation code. This may be useful to compare modes, especially if there are other loaders/plugins involved in the compilation. requires Node.js >= 8.5.0

• typescript string: If supplied this is a custom path where typescript can be found. Defaults to require.resolve('typescript').

• resolveModuleNameModule and resolveTypeReferenceDirectiveModule string: Both of those options refer to files on the disk that respectively export a resolveModuleName or a resolveTypeReferenceDirectiveModule function. These functions will be used to resolve the import statements and the <reference types="..."> directives instead of the default TypeScript implementation. Check the following code for an example of what those functions should look like:

  Code sample

  const { resolveModuleName } = require(`ts-pnp`);
  
  exports.resolveModuleName = (
    typescript,
    moduleName,
    containingFile,
    compilerOptions,
    resolutionHost
  ) => {
    return resolveModuleName(
      moduleName,
      containingFile,
      compilerOptions,
      resolutionHost,
      typescript.resolveModuleName
    );
  };
  
  exports.resolveTypeReferenceDirective = (
    typescript,
    moduleName,
    containingFile,
    compilerOptions,
    resolutionHost
  ) => {
    return resolveModuleName(
      moduleName,
      containingFile,
      compilerOptions,
      resolutionHost,
      typescript.resolveTypeReferenceDirective
    );
  };
  

Different behaviour in watch mode

If you turn on webpacks watch mode the fork-ts-checker-notifier-webpack-plugin will take care of logging type errors, not webpack itself. That means if you set silent: true you won't see type errors in your console in watch mode.

You can either set silent: false to show the logging from fork-ts-checker-notifier-webpack-plugin or set async: false. Now webpack itself will log type errors again, but note that this can slow down your builds depending on the size of your project.

Notifier

You may already be using the excellent webpack-notifier plugin to make build failures more obvious in the form of system notifications. There's an equivalent notifier plugin designed to work with the fork-ts-checker-webpack-plugin. It is the fork-ts-checker-notifier-webpack-plugin and can be found here. This notifier deliberately has a similar API as the webpack-notifier plugin to make migration easier.

Known Issue Watching Non-Emitting Files

At present there is an issue with the plugin regarding the triggering of type-checking when a change is made in a source file that will not emit js. If you have a file which contains only interfaces and / or types then changes to it will not trigger the type checker whilst in watch mode. Sorry about that.

We hope this will be resolved in future; the issue can be tracked here.

Plugin Hooks

This plugin provides some custom webpack hooks (all are sync):

Hook Access Key	Description	Params
cancel	Cancellation has been requested	cancellationToken
waiting	Waiting for results	-
serviceBeforeStart	Async plugin that can be used for delaying fork-ts-checker-service-start	-
serviceStart	Service will be started	tsconfigPath, memoryLimit
serviceStartError	Cannot start service	error
serviceOutOfMemory	Service is out of memory	-
receive	Plugin receives diagnostics and lints from service	diagnostics, lints
emit	Service will add errors and warnings to webpack compilation ('build' mode)	diagnostics, lints, elapsed
done	Service finished type checking and webpack finished compilation ('watch' mode)	diagnostics, lints, elapsed

Accessing plugin hooks

To access plugin hooks and tap into the event, we need to use the getCompilerHooks static method. When we call this method with a webpack compiler instance, it returns the series of tapable hooks where you can pass in your callbacks.

// require the plugin
const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
// setup compiler with the plugin
const compiler = webpack({
  // .. webpack config
});
// Optionally add the plugin to the compiler
// **Don't do this if already added through configuration**
new ForkTsCheckerWebpackPlugin({
  silent: true,
  async: true
}).apply(compiler);
// Now get the plugin hooks from compiler
const tsCheckerHooks = ForkTsCheckerWebpackPlugin.getCompilerHooks(compiler);
// These hooks provide access to different events
// =================================================== //
// The properties of tsCheckerHooks corresponds to the //
// Hook Access Key of the table above.                 //
// =================================================== //
// Example, if we want to run some code when plugin has received diagnostics
// and lint
tsCheckerHooks.receive.tap('yourListenerName', (diagnostics, lint) => {
  // do something with diagnostics, perhaps show custom message
  console.log(diagnostics);
});
// Say we want to show some message when plugin is waiting for typecheck results
tsCheckerHooks.waiting.tap('yourListenerName', () => {
  console.log('waiting for typecheck results');
});

Calling .tap() on any hooks, requires two arguments.

name (string)

The first argument passed to .tap is the name of your listener callback (yourListenerName). It doesn't need to correspond to anything special. It is intended to be used internally as the name of the hook.

callback (function)

The second argument is the callback function. Depending on the hook you are tapping into, several arguments are passed to the function. Do check the table above to find out which arguments are passed to which hooks.

Accessing hooks on Webpack Multi-Compiler instance

The above method will not work on webpack multi compiler instance. The reason is getCompilerHooks expects (at lease as of now) the same compiler instance to be passed where the plugin was attached. So in case of multi compiler, we need to access individual compiler instances.

const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
// setup multi compiler with the plugin
const compiler = webpack([
  {
    // .. webpack config
  },
  {
    // .. webpack config
  }
]);

// safely determine if instance is multi-compiler
if ('compilers' in compiler) {
  compiler.compilers.forEach(singleCompiler => {
    // get plugin hooks from the single compiler instance
    const tsCheckerHooks = ForkTsCheckerWebpackPlugin.getCompilerHooks(
      singleCompiler
    );
    // now access hooks just like before
    tsCheckerHooks.waiting.tap('yourListenerName', () => {
      console.log('waiting for typecheck results');
    });
  });
}

Vue

• Turn on the vue option in the plugin in your webpack config:

new ForkTsCheckerWebpackPlugin({
  vue: true
});

Optionally change default vue-template-compiler to nativescript-vue-template-compiler if you use nativescript-vue

new ForkTsCheckerWebpackPlugin({
  vue: { enabled: true, compiler: 'nativescript-vue-template-compiler' }
});

• To activate TypeScript in your .vue files, you need to ensure your script tag's language attribute is set to ts or tsx (also make sure you include the .vue extension in all your import statements as shown below):

<script lang="ts">
  import Hello from '@/components/hello.vue';

  // ...
</script>

• Ideally you are also using ts-loader (in transpileOnly mode). Your Webpack config rules may look something like this:

{
  test: /\.ts$/,
  loader: 'ts-loader',
  include: [resolve('src'), resolve('test')],
  options: {
    appendTsSuffixTo: [/\.vue$/],
    transpileOnly: true
  }
},
{
  test: /\.vue$/,
  loader: 'vue-loader',
  options: vueLoaderConfig
},

• Ensure your tsconfig.json includes .vue files:

// tsconfig.json
{
  "include": [
    "src/**/*.ts",
    "src/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

• It accepts any wildcard in your TypeScript configuration:

// tsconfig.json
{
  "compilerOptions": {

    // ...

    "baseUrl": ".",
    "paths": {
      "@/*": [
        "src/*"
      ],
      "~/*": [
        "src/*"
      ]
    }
  }
}

// In a .ts or .vue file...
import Hello from '@/components/hello.vue'

• If you are working in VSCode, you can get the Vetur extension to complete the developer workflow.

Credits

This plugin was created in Realytics in 2017. Thank you for supporting Open Source.

License

MIT License